Skip Headers

Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# OCI Pin, Unpin, and Free Functions

This section describes the OCI pin unpin, and free functions.

Table 17-11 Pin, Unpin, and Free Functions

Function/Page | Purpose
--- | ---
OCICacheFree() | Free objects in the cache
OCICacheUnpin() | Unpin persistent objects in cache or connection
OCIObjectArrayPin() | Pin an array of references
OCIObjectFree() | Free a previously allocated object
OCIObjectPin() | Pin an object
OCIObjectPinCountReset() | Unpin an object to zero pin count
OCIObjectPinTable() | Pin a table object with a given duration
OCIObjectUnpin() | Unpin an object

## OCICacheFree()

Purpose

Frees all objects and values in the cache for the specified connection.

Syntax

    sword OCICacheFree ( OCIEnv              *env,
                         OCIError            *err,
                         CONST OCISvcCtx     *svc );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

svc (IN)

  An OCI service context.

Comments

If a connection is specified, this function frees the persistent objects, transient objects and values allocated for that connection. Otherwise, all persistent objects, transient objects and values in the object cache are freed. Objects are freed regardless of their pin count.

See Also: See "OCIObjectFree()" for more information about freeing an instance.

Related Functions

OCIObjectFree()

## OCICacheUnpin()

Purpose

Unpins persistent objects.

Syntax

    sword OCICacheUnpin ( OCIEnv              *env,
                          OCIError            *err,
                          CONST OCISvcCtx     *svc );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

svc (IN)

  An OCI service context handle. The objects on the specified connection are unpinned.

Comments

This function completely unpins all of the persistent objects for the given connection. The pin count for the objects is reset to zero.

See Also: For more information about pinning and unpinning, see "Pinning an Object", and "Pin Count and Unpinning".

Related Functions

OCIObjectUnpin()

## OCIObjectArrayPin()

Purpose

Pins an array of references.

Syntax

    sword OCIObjectArrayPin ( OCIEnv            *env,
                              OCIError          *err,
                              OCIRef            **ref_array,
                              ub4               array_size,
                              OCIComplexObject  **cor_array,
                              ub4               cor_array_size,
                              OCIPinOpt         pin_option,
                              OCIDuration       pin_duration,
                              OCILockOpt        lock,
                              dvoid             **obj_array,
                              ub4               *pos );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

ref_array (IN)

  Array of references to be pinned

array_size (IN)

  Number of elements in the array of references

cor_array

  An array of COR handles corresponding to the objects being pinned.

cor_array_size

  The number of elements in `cor_array`.

pin_option (IN)

  Pin option.

  See Also: "OCIObjectPin()"

pin_duration (IN)

  Pin duration. See `OCIObjectPin()`.

lock (IN)

  Lock option. See `OCIObjectPin()`.

obj_array (OUT)

  If this argument is not `NULL`, the pinned objects will be returned in the array. The user must allocate this array with element type being `dvoid *`. The size of this array is identical to `array_size`.

pos (OUT)

  If there is an error, this argument indicates the element that is causing the error. Note that this argument is set to 1 for the first element in the `ref_array`.

Comments

All the pinned objects are retrieved from the database in one network round trip. If the user specifies an output array (`obj_array`), then the address of the pinned objects will be assigned to the elements in the array.

Related Functions

OCIObjectPin()

## OCIObjectFree()

Purpose

Frees and unpins an object instance.

Syntax

    sword OCIObjectFree ( OCIEnv          *env,
                          OCIError        *err,
                          dvoid           *instance,
                          ub2             flags );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

instance (IN)

  Pointer to a standalone instance. If it is an object, it must be pinned.

flags (IN)

  If `OCI_OBJECTFREE_FORCE` is passed, free the object even if it is pinned or dirty. If `OCI_OBJECTFREE_NONULL` is passed, the `NULL` structure is not freed.

Comments

This function deallocates all the memory allocated for an object instance, including the `NULL` structure. The following rules apply for different instance types:

For Persistent Objects

  This function returns an error if the client is attempting to free a dirty persistent object that has not been flushed. The client should either flush the persistent object, unmark it, or set the parameter `flags` to `OCI_OBJECTFREE_FORCE`.

  This function calls `OCIObjectUnpin()` once to check if the object can be completely unpin. If it succeeds, the rest of the function proceeds to free the object. If it fails, then an error is returned unless the parameter `flags` is set to `OCI_OBJECTFREE_FORCE`.

  Freeing a persistent object in memory does not change the persistent state of that object at the server. For example, the object remains locked after the object is freed.

For Transient Objects

  This function will call `OCIObjectUnpin()` once to check if the object can be completely unpin. If it succeeds, the rest of the function will proceed to free the object. If it fails, then an error is returned unless the parameter `flags` is set to `OCI_OBJECTFREE_FORCE`.

For Values

  The memory of the object is freed immediately.

Related Functions

OCICacheFree()

## OCIObjectPin()

Purpose

Pin a referenceable object.

Syntax

    sword OCIObjectPin ( OCIEnv              *env,
                         OCIError            *err,
                         OCIRef              *object_ref,
                         OCIComplexObject    *corhdl,
                         OCIPinOpt           pin_option,
                         OCIDuration         pin_duration,
                         OCILockOpt          lock_option,
                         dvoid               **object );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

object_ref (IN)

  The reference to the object.

corhdl (IN)

  Handle for complex object retrieval.

pin_option (IN)

  Used to specify the copy of the object that is to be retrieved.

pin_duration (IN)

  The duration of which the object is being accessed by a client. The object is implicitly unpinned at the end of the pin duration. If `OCI_DURATION_NULL` is passed, there is no pin promotion if the object is already loaded into the cache. If the object is not yet loaded, then the pin duration is set to `OCI_DURATION_DEFAULT` in the case of `OCI_DURATION_NULL`.

lock_option (IN)

  Lock option (for example, exclusive). If a lock option is specified, the object is locked in the server. Note, the lock status of an object can also be retrieved by calling `OCIObjectIsLocked()`. Valid values include:

- `OCI_LOCK_NONE` - for no lock

- `OCI_LOCK_X` - for an exclusive lock

- `OCI_LOCK_X_NOWAIT` - for an exclusive lock with the `NOWAIT` option.

  See Also: For information about the `NOWAIT` option, see "Locking with the NOWAIT Option".

object (OUT)

  The pointer to the pinned object.

Comments

This function pins a referenceable object instance given the object reference. The process of pinning serves two purposes:

- locate an object given its reference. This is done by the object cache which keeps track of the objects in the object cache.

- notify the object cache that a persistent object is being in use such that the persistent object cannot be aged out. Since a persistent object can be loaded from the server whenever is needed, the memory utilization can be increased if a completely unpinned persistent object can be freed (aged out), even before the allocation duration is expired. An object can be pinned many times. A pinned object will remain in memory until it is completely unpinned.

  See Also: See "OCIObjectUnpin()".

For Persistent Objects

  When pinning a persistent object, if it is not in the cache, the object will be fetched from the persistent store. The allocation duration of the object is session. If the object is already in the cache, it is returned to the client. The object will be locked in the server if a lock option is specified.

  This function will return an error for a non-existent object.

  A pin option is used to specify the copy of the object that is to be retrieved:

- If `pin_option` is `OCI_PIN_ANY` (pin any), then if the object is already in the object cache, return this object. Otherwise, the object is retrieved from the database. In this case, it is the same as `OCI_PIN_LATEST`. This option is useful when the client knows that he has the exclusive access to the data in a session.

- If `pin_option` is `OCI_PIN_LATEST` (pin latest), if the object is not locked, it is retrieved from the database. If the object is cached, it is refreshed with the latest version. See `OCIObjectRefresh()` for more information about refreshing. If the object is already pinned in the cache and marked dirty, then a pointer to that object is returned. The object will not be refreshed from the database.

- If `pin_option` is `OCI_PIN_RECENT` (pin recent), if the object is loaded into the cache in the current transaction, the object is returned. If the object is not loaded in the current transaction, the object is refreshed from the server.

For Transient Objects

  This function will return an error if the transient object has already been freed. This function does not return an error if an exclusive lock is specified in the lock option.

Related Functions

OCIObjectUnpin(), OCIObjectPinCountReset()

## OCIObjectPinCountReset()

Purpose

Completely unpins an object, setting its pin count to zero.

Syntax

    sword OCIObjectPinCountReset ( OCIEnv        *env,
                                   OCIError      *err,
                                   dvoid         *object );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

object (IN)

  A pointer to an object, which must already be pinned.

Comments

This function completely unpins an object, setting its pin count to zero. When an object is completely unpinned, it can be freed implicitly by the OCI at any time without error. The following rules apply for specific object types:

For Persistent Objects

  When a persistent object is completely unpinned, it becomes a candidate for aging. The memory of an object is freed when it is aged out. Aging is used to maximize the utilization of memory. An dirty object cannot be aged out unless it is flushed.

For Transient Objects

  The pin count of the object is decremented. A transient can be freed only at the end of its allocation duration or when it is explicitly freed by calling `OCIObjectFree()`.

For Values

  This function will return an error for value.

  See Also: "Pin Count and Unpinning"

Related Functions

OCIObjectPin(), OCIObjectUnpin()

## OCIObjectPinTable()

Purpose

Pins a table object for a specified duration.

Syntax

    sword OCIObjectPinTable ( OCIEnv             *env,
                              OCIError           *err,
                              CONST OCISvcCtx    *svc,
                              CONST OraText      *schema_name,
                              ub4                s_n_length,
                              CONST OraText      *object_name,
                              ub4                o_n_length,
                              dvoid              *not_used,
                              OCIDuration        pin_duration,
                              dvoid              **object );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

svc (IN)

  The OCI service context handle.

schema_name (IN) [optional]

  The schema name of the table.

s_n_length (IN) [optional]

  The length of the schema name indicated in `schema_name`, in bytes.

object_name (IN)

  The name of the table.

o_n_length (IN)

  The length of the table name specified in `object_name`, in bytes.

not_used (IN/OUT)

  This parameter is not currently used. Pass as `NULL`.

pin_duration (IN)

  The pin duration.

  See Also: "OCIObjectPin()".

object (OUT)

  The pinned table object.

Comments

This function pins a table object with the specified pin duration. The client can unpin the object by calling `OCIObjectUnpin()`.

The table object pinned by this call can be passed as a parameter to `OCIObjectNew()` to create a standalone persistent object.

Note: The TDO (array of TDOs or table definition) obtained by this function will belong to the logical partition of the cache corresponding to the service handle (connection) passed in. If TDOs or tables are used across logical partitions, then the behavior is not known and may change between releases.

Related Functions

OCIObjectPin(), OCIObjectUnpin()

## OCIObjectUnpin()

Purpose

Unpins an object.

Syntax

    sword OCIObjectUnpin ( OCIEnv        *env,
                           OCIError      *err,
                           dvoid         *object );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

object (IN)

  A pointer to an object, which must already be pinned.

Comments

There is a pin count associated with each object which is incremented whenever an object is pinned. When the pin count of the object is zero, the object is said to be completely unpinned. An unpinned object can be freed implicitly by the OCI at any time without error.

This function unpins an object. An object is completely unpinned when any of the following is true:

1. The object's pin count reaches zero (that is, it is unpinned a total of N times after being pinned a total of N times).

2. It is the end of the object's pin duration.

3. The function `OCIObjectPinCountReset()` is called on the object.

When an object is completely unpinned, it can be freed implicitly by the OCI at any time without error.

The following rules apply for unpinning different types of objects:

For Persistent Objects

  When a persistent object is completely unpinned, it becomes a candidate for aging. The memory of an object is freed when it is aged out. Aging is used to maximize the utilization of memory. An dirty object cannot be aged out unless it is flushed.

For Transient Objects

  The pin count of the object is decremented. A transient can be freed only at the end of its allocation duration or when it is explicitly deleted by calling `OCIObjectFree()`.

For Values

  This function returns an error for values.

Related Functions

OCIObjectPin(), OCIObjectPinCountReset()